git faq : draft and rfc
hi,
After a quick talk on irc with pasky, fonseca and Tv, I've started to write a git faq starting with questions I had and they have suggested.
I've setted up a git repos : http://git.librium.org/git_faq.git (atm it's on my DSL link, so it could be slow, should move soon)
The faq is available in both docbook xml and text format (don't know what you prefer).
You can see the html output there : http://koalabs.org/~ange/git_faq/faq.html
and the text file : http://koalabs.org/~ange/git_faq/faq.txt
if needed I can write specific xsl stylesheets to handle better or more suited output.
Comments and suggestions are welcome (on the content, the form, format, etc ...) I'll try to add questions from the archives of this ml, I'm also open to any suggestions.
Here is a first (text) version :
----
. Why the 'git' name ?
As Linus' own words as the inventor of git :
"git" can mean anything, depending on your mood.
- random three-letter combination that is pronounceable, and not actually used by any common UNIX command. The fact that it is a mispronunciation of "get" may or may not be relevant.
- stupid. contemptible and despicable. simple. Take your pick from the dictionary of slang.
- "global information tracker": you're in a good mood, and it actually works for you. Angels sing, and a light suddenly fills the room.
- "goddamn idiotic truckload of sh*t": when it breaks
. Can I use my git public repository in a shared way ?
Yes. Use cg-admin-setuprepo -g or do git-init-db --shared and some additional stuff. It's ok that refs aren't group writable, it's enough the directory is. See Cogito README or GIT's cvs-migration doc, "Emulating the CVS Development Model" for details.
. Git commit is dying telling me "fatal : empty ident <user@myhost> not allowed", what's wrong ?
Make sure your Full Name is not empty in chsh or the 5th field of your user line in /etc/passwd isn't empty. If you @myhost is empty make sure your hostname is correctly set.
. What's the difference between fetch and pull ? Fetch : download objects and a head from another repository. Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.
. Can I tell git to ignore files ?
Yes. Put the files path in the repository in the .git/info/exclude file.
. Can I import from cvs ?
Yes. Use git-cvsimport. See the cvs-migration doc for more details.
. Can I import from svn ?
Yes. Use git-svnimport. See the svn-import doc for more details.
. What can I use to setup a public repository ?
A ssh server, an http server, or the git-daemon.
See the tutorial for more details.
--
Thom/ange
Quoted 4 lines · Thomas Riboulet
. What's the difference between fetch and pull ? Fetch : download objects and a head from another repository. Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.
Surely you are using a pull to mean fetch here, Shouldn't this be
Fetch: download objects and a head from another repository.
Pull: fetch (as defined above) and then merge this with current development
or something
Signature · 3 lines
Alan Chandler http://www.chandlerfamily.org.uk Open Source. It's the difference between trust and antitrust.
Dear diary, on Thu, Feb 16, 2006 at 01:36:20AM CET, I got a letter where Thomas Riboulet <[email protected]> said that...
Quoted 5 lines
. Git commit is dying telling me "fatal : empty ident <user@myhost> not allowed", what's wrong ?
Make sure your Full Name is not empty in chsh or the 5th field of your user line in/etc/passwdisn't empty. If you @myhost is empty make sure your hostname is correctly set.
Please also mention GIT_AUTHOR_NAME; chsh may be frequently unavailable.
Quoted 4 lines
. What's the difference between fetch and pull ? Fetch : download objects and a head from another repository. Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.
This could do with a little more elaboration as well. Nice inspiration might be <[email protected]>.
Quoted 2 lines
. Can I tell git to ignore files ?
Yes. Put the files path in the repository in the .git/info/exclude file.
Or .gitignore in the tree itself. .git/info/exclude is only for your particular checkout while .gitignore is what matters for all and everyone's checkouts of the project.
Quoted 3 lines
. What can I use to setup a public repository ?
A ssh server, an http server, or the git-daemon.
See the tutorial for more details.
Well this is about how to make it available, not how to use it.
The repository should be set up by cg-admin-setuprepo or git-init-db --shared and normally does not have a working tree attached. You can fetch from such a repository either over:
* the GIT protocol (you need to run git-daemon)
* SSH (you can set up a git-use-only account using git-shell)
* rsync (has important disadvantages but it is currently the fastest way to do the initial checkout)
* or the HTTP protocol (any reasonable webhosting will do, but you need to run git-update-server-info after each repository update; if you used cg-admin-setuprepo to set it up, this will be done automatically, otherwise you may enable it in the post-update hook - see .git/hooks/post-update).
You can push to such a repository over:
* SSH
* HTTP DAV (you will need to specially configure your HTTP server for this)
Obviously, you can also fetch/push from/to a repository locally if it is available in the local filesystem structure.
Signature · 5 lines
Petr "Pasky" Baudis Stuff: http://pasky.or.cz/ Of the 3 great composers Mozart tells us what it's like to be human, Beethoven tells us what it's like to be Beethoven and Bach tells us what it's like to be the universe. -- Douglas Adams
Quoted 9 lines · Petr Baudis
Dear diary, on Thu, Feb 16, 2006 at 01:36:20AM CET, I got a letter where Thomas Riboulet <[email protected]> said that...
Quoted 5 lines
. Git commit is dying telling me "fatal : empty ident <user@myhost> not allowed", what's wrong ?
Make sure your Full Name is not empty in chsh or the 5th field of your user line in/etc/passwdisn't empty. If you @myhost is empty make sure your hostname is correctly set.Please also mention
GIT_AUTHOR_NAME; chsh may be frequently unavailable.
ok
Quoted 8 lines
Quoted 5 lines
. What's the difference between fetch and pull ? Fetch : download objects and a head from another repository. Pull : pull and merge from another repository.
See man git-fetch and git-pull for more.This could do with a little more elaboration as well. Nice inspiration might be <[email protected]>.
ok, I'll as soon as I manage to get it :/
Quoted 8 lines
Quoted 3 lines
. Can I tell git to ignore files ?
Yes. Put the files path in the repository in the .git/info/exclude file.Or .gitignore in the tree itself. .git/info/exclude is only for your particular checkout while .gitignore is what matters for all and everyone's checkouts of the project.
ok, added
Quoted 20 lines
Quoted 3 lines
. What can I use to setup a public repository ?
A ssh server, an http server, or the git-daemon.
See the tutorial for more details.Well this is about how to make it available, not how to use it.
The repository should be set up by cg-admin-setuprepo or git-init-db --shared and normally does not have a working tree attached. You can fetch from such a repository either over:
* the GIT protocol (you need to run git-daemon)
* SSH (you can set up a git-use-only account using git-shell)
* rsync (has important disadvantages but it is currently the fastest way to do the initial checkout)
* or the HTTP protocol (any reasonable webhosting will do, but you need to run git-update-server-info after each repository update; if you used cg-admin-setuprepo to set it up, this will be done automatically, otherwise you may enable it in the post-update hook - see .git/hooks/post-update).
Quoted 9 lines
You can push to such a repository over:
* SSH
* HTTP DAV (you will need to specially configure your HTTP server for this)Obviously, you can also fetch/push from/to a repository locally if it is available in the local filesystem structure.
the initial aim of that question was simply to tell svn people (and others) what can be used to setup a public repos.
isn't it a bit too much for a faq ? maybe add some things to the present answer and put this question in the "general questions" section (see below), and add more details in the "usage" section ?
Quoted 7 lines
--
Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
Of the 3 great composers Mozart tells us what it's like to be human, Beethoven tells us what it's like to be Beethoven and Bach tells us what it's like to be the universe. -- Douglas Adams
ok added (and pushed) the :
- taylor qa
- the git import bk qa
- GIT_AUTHOR_NAME
I'll separate the questions between the following sections :
- general questions (who, when, where, ...)
- usage : commands, errors ...
I'm planning on removing the text format faq and handle it as I handle the html one : through the docbook. ok ?
--
Thom/ange
Maybe another question :
How could I merge a branch 'to-merge' with structure a/b/c into branch 'master' with structure g/h/i and include files from branch 'to-merge' in g/h/i ?
I don't know if it's very clear
--
Beber
#e.fr@freenode
Quoted 5 lines · Bertrand Jacquin
Maybe another question :
How could I merge a branch 'to-merge' with structure a/b/c into branch 'master' with structure g/h/i and include files from branch 'to-merge' in g/h/i ?
Like as Junio with branch man and html.
Quoted 7 lines
I don't know if it's very clear
--
Beber
#e.fr@freenode
--
Beber
#e.fr@freenode
PATCH 1/1 Convert the git faq to asciidoc
In reply to Thomas Riboulet---
Thomas Riboulet <[email protected]> wrote Thu, Feb 16, 2006:
Quoted 3 lines
Comments and suggestions are welcome (on the content, the form, format, etc ...) I'll try to add questions from the archives of this ml, I'm also open to any suggestions.
As promissed on the #git channel this patch converts the faq to asciidoc format, with a few enhancements such as links to manpages and a TOC.
Previews at
http://www.diku.dk/hjemmesider/studerende/fonseca/git/git-faq.{html,txt,xml}.
---
Makefile | 23 ++++++++ faq.conf | 19 +++++++ faq.txt | 175 ++++++++++++++++++++++++++++++++++++++++++-------------------- 3 files changed, 161 insertions(+), 56 deletions(-)
Makefile new file +23 -0
@@ -0,0 +1,23 @@ +all: git-faq.html git-faq.xml git-faq.txt + +clean: + rm -f git-faq.html git-faq.xml git-faq.txt faq-toc.txt + +git-faq.html git-faq.xml git-faq.txt: faq.txt faq-toc.txt + +git-faq.xml: + asciidoc -f faq.conf -b docbook -d article -o $@ faq.txt + +git-faq.html: faq.txt faq-toc.txt + asciidoc -f faq.conf -b xhtml11 -d article -o $@ faq.txt + +git-faq.txt: git-faq.html + elinks --no-numbering --no-references --dump $< > $@ + +faq-toc.txt: faq.txt + sed -n '/^\[\[/,/--/p' < $< | while read line; do \ + case "$$line" in \ + "[["*"]]") echo -n ". <<$$line, " | sed 's/\[\[\(.*\)\]\]/\1/' ;; \ + --*) echo ">>" ;; \ + *) echo -n "$$line " ;; \ + esac; done > $@
faq.conf new file +19 -0
@@ -0,0 +1,19 @@ +# AsciiDoc FAQ definitions + +[attributes] +gitdoc-base=http://kernel.org/pub/software/scm/git/docs/ +cgdoc-base=http://kernel.org/pub/software/scm/cogito/docs/ + +ifdef::backend-docbook[] +[gitdoc-inlinemacro] +<ulink url="{gitdoc-base}{target}.html">{0}</ulink> +[cgdoc-inlinemacro] +<ulink url="{cgdoc-base}{target}.html">{0}</ulink> +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[gitdoc-inlinemacro] +<a href="{gitdoc-base}{target}.html">{0}</a> +[cgdoc-inlinemacro] +<a href="{cgdoc-base}{target}.html">{0}</a> +endif::backend-xhtml11[]
faq.txt +119 -56
187 lines not on this page · raw message
Signature · 1 line
Jonas Fonseca
Re: [PATCH] Convert the git faq to asciidoc
Quoted 270 lines · Jonas Fonseca
Signed-off-by Jonas Fonseca <[email protected]>---
Thomas Riboulet <[email protected]> wrote Thu, Feb 16, 2006:
Quoted 3 lines
Comments and suggestions are welcome (on the content, the form, format, etc ...) I'll try to add questions from the archives of this ml, I'm also open to any suggestions.
As promissed on the #git channel this patch converts the faq to asciidoc format, with a few enhancements such as links to manpages and a TOC.
Previews at
http://www.diku.dk/hjemmesider/studerende/fonseca/git/git-faq.{html,txt,xml}.---
Makefile | 23 ++++++++ faq.conf | 19 +++++++ faq.txt | 175 ++++++++++++++++++++++++++++++++++++++++++-------------------- 3 files changed, 161 insertions(+), 56 deletions(-)Makefile new file +23
-0@@ -0,0 +1,23 @@ +all: git-faq.html git-faq.xml git-faq.txt + +clean: + rm -f git-faq.html git-faq.xml git-faq.txt faq-toc.txt + +git-faq.html git-faq.xml git-faq.txt: faq.txt faq-toc.txt + +git-faq.xml: + asciidoc -f faq.conf -b docbook -d article -o $@ faq.txt + +git-faq.html: faq.txt faq-toc.txt + asciidoc -f faq.conf -b xhtml11 -d article -o $@ faq.txt + +git-faq.txt: git-faq.html + elinks --no-numbering --no-references --dump $< > $@ + +faq-toc.txt: faq.txt + sed -n '/^\[\[/,/--/p' < $< | while read line; do \ + case "$$line" in \ + "[["*"]]") echo -n ". <<$$line, " | sed 's/\[\[\(.*\)\]\]/\1/' ;; \ + --*) echo ">>" ;; \ + *) echo -n "$$line " ;; \ + esac; done > $@faq.conf new file +19
-0@@ -0,0 +1,19 @@ +# AsciiDoc FAQ definitions + +[attributes] +gitdoc-base=http://kernel.org/pub/software/scm/git/docs/ +cgdoc-base=http://kernel.org/pub/software/scm/cogito/docs/ + +ifdef::backend-docbook[] +[gitdoc-inlinemacro] +<ulink url="{gitdoc-base}{target}.html">{0}</ulink> +[cgdoc-inlinemacro] +<ulink url="{cgdoc-base}{target}.html">{0}</ulink> +endif::backend-docbook[] + +ifdef::backend-xhtml11[] +[gitdoc-inlinemacro] +<a href="{gitdoc-base}{target}.html">{0}</a> +[cgdoc-inlinemacro] +<a href="{cgdoc-base}{target}.html">{0}</a> +endif::backend-xhtml11[]faq.txt +119
-57@@ -1,68 +1,131 @@ -Why the 'git' name ? - -As Linus' own words as the inventor of git : "git" can mean anything, depending on your mood. - -* random three-letter combination that is pronounceable, and not actually used by any common UNIX command. The fact that it is a mispronunciation of "get" may or may not be relevant. -* stupid. contemptible and despicable. simple. Take your pick from the dictionary of slang. -* global information tracker": you're in a good mood, and it actually works for you. Angels sing, and a light suddenly fills the room. -* "goddamn idiotic truckload of sh*t": when it breaks - - -Can I share a git public repository and use it in a CVS way ? - -Use cg-admin-setuprepo -g or do git-init-db --shared and some additional stuff. It's ok that refs aren't group writable, it's enough the directory is. See Cogito README or GIT's cvs-migration doc, "Emulating the CVS Development Model" for details. - - -Git commit is dying telling me "fatal : empty ident <user@myhost> not allowed" , what's wrong ? - -Make sure your Full Name is not empty in chsh or the 5th field of your user line in /etc/passwd isn't empty. You can also set the GIT_AUTHOR_NAME environment variable. If you @myhost is empty make sure your hostname is correctly set. -What's the difference between fetch and pull ? - -Fetch : download objects and a head from another repository. -Pull : fetch (as defined above) and merge with the current development. -See man git-fetch and git-pull or the tutorials for more details. - - - -Can I tell git to ignore files ? - -Yes. If you want to ignore files localy (only for you in your local work copy) put the files path in the repository in the .git/info/exclude file. - -If you want to make the ignore matters for all and everyone who checkouts the project you have to put the files path in the .gitignore in the tree itself. - - -Can I import from cvs ? - -Yes. Use git-cvsimport. See the cvs-migration doc for more details. - - -Can I import from svn ? - -Yes. Use git-svnimport. See the svn-import doc for more details. +The git FAQ +=========== +:Author: Thomas Riboulet +:CorpAuthor: git mailing list + +////////////////////////////////////////////////////////////////////////////// +A note about required info for FAQ entries. Please use the following template: + + [[question-id]] + question? + --------- + answer. + +The question-id + question will be used for generating a table of contents. +////////////////////////////////////////////////////////////////////////////// + +// DocBook derived output will (hopefully) have it's own TOC +ifdef::backend-xhtml11[] +include::faq-toc.txt[] +endif::backend-xhtml11[] + +[[git-name]] +Why the 'git' name? +------------------- +In Linus' own words as the inventor of git: "git" can mean anything, depending +on your mood: + + - random three-letter combination that is pronounceable, and not actually + used by any common UNIX command. The fact that it is a mispronunciation of + "get" may or may not be relevant. + - stupid. contemptible and despicable. simple. Take your pick from the + dictionary of slang. + - global information tracker": you're in a good mood, and it actually works + for you. Angels sing, and a light suddenly fills the room. + - "goddamn idiotic truckload of sh*t": when it breaks + + +[[repo-sharing]]] +Can I share a git public repository and use it in a CVS way? +------------------------------------------------------------ +Use cg-admin-setuprepo -g or do git-init-db --shared and some additional +stuff. It's ok that refs aren't group writable, it's enough the directory is. +See Cogito README or GIT's cvs-migration doc, "Emulating the CVS Development +Model" for details. + + +[[empty-ident]] +Git commit is dying telling me "fatal: empty ident <user@myhost> not allowed", what's wrong? +-------------------------------------------------------------------------------------------- +Make sure your Full Name is not empty in chsh or the 5th field of your user +line in `/etc/passwd` isn't empty. You can also set the `GIT_AUTHOR_NAME` +environment variable. If your @myhost is empty make sure your hostname is +correctly set. Use gitdoc:git-var[`git-var -l`] to make git display user +identity variables. + + +[[fetch-vs-pull]] +What's the difference between fetch and pull? +--------------------------------------------- +The short definition is: + +Fetch:: Download objects and a head from another repository. +Pull:: Fetch (as defined above) and merge with the current development. + +See the gitdoc:git-fetch[git-fetch(1)] and gitdoc:git-pull[git-pull(1)] +manpages or the tutorials for more details. + + +[[gitignore]] +Can I tell git to ignore files? +------------------------------- +Yes. If you want to ignore files localy (only for you in your local work copy) +put the files path in the repository in the `.git/info/exclude` file. + +If you want to make the ignore matters for all and everyone who checkouts the +project you have to put the files path in the `.gitignore` in the tree itself. + + +[[import-cvs]] +Can I import from CVS? +---------------------- +Yes. Use git-cvsimport. See the gitdoc:git-cvsimport[git-cvsimport(1)] or +gitdoc:cvs-migration[the CVS migration doc] for more detail. + + +[[import-svn]] +Can I import from svn? +---------------------- +Yes. Use git-svnimport. See gitdoc:git-svnimport[git-svnimport(1)] for more +details. +[[import-arch]] Can I import from arch/baz/tla? - -Yes. Use git-archimport. +------------------------------- +Yes. Use git-svnimport. See gitdoc:git-archimport[git-archimport(1)] for more +details. +[[import-others]] Can I import from others? +------------------------- +Maybe -- check if http://www.darcs.net/DarcsWiki/Tailor[tailor.py] can do it. -Maybe -- check if tailor.py can do it. Check http://www.darcs.net/DarcsWiki/Tailor. - - -How old linus bk repos have been import to git ? +[[linux-bk]] +How was the old Linux BitKeeper repository imported into git? +------------------------------------------------------------- Using the CVS gateway, via git-cvsimport. -What can I use to setup a public repository ? - -A ssh server, an http server, or the git-daemon. See the tutorial for more details. - - -Why won't git let me change to a different branch using "git checkout <branch>" or "git checkout -b <branch>"? - -Instead it just says: fatal: Entry 'foo.c' not uptodate. Cannot merge. +[[public-repo]] +What can I use to setup a public repository? +-------------------------------------------- +A SSH server, an HTTP server, or the gitdoc:git-daemon[git-daemon]. See the +tutorial for more details. + + +[[change-branch]] +Why won't git let me change to a different branch? +-------------------------------------------------- +Using "git checkout <branch>" or "git checkout -b <branch>" it just says: + + fatal: Entry 'foo.c' not uptodate. Cannot merge. + +You have changes to files in your working directory that will be overwritten, +removed or otherwise lost if the checkout and change to the new branch were to +proceed. To fix this you may either check your changes in, create a patch of +your changes and revert your files, or use the "-m" flag like this: -You have changes to files in your working directory that will be overwritten, removed or otherwise lost if the checkout and change to the new branch were to proceed. To fix this you may either check your changes in, create a patch of your changes and revert your files, or use the "-m" flag like this: git checkout -m -b my-branch + git checkout -m -b my-branch --
Quoted 2 lines
Jonas Fonseca
hi,
ok seems much easier than docbook to write, I've commited your changes, I'll push them when I'll be back home.
I've tested the docbook file generated, works fine
thanks
--
Thom/ange
http://ange.librium.org
Quoted 5 lines · Thomas Riboulet
. Can I import from cvs ?
Yes. Use git-cvsimport. See the cvs-migration doc for more details.. Can I import from svn ?
Yes. Use git-svnimport. See the svn-import doc for more details.
+ Can I import from arch/baz/tla? Use git-archimport.
+ Can I import from others? Maybe -- check if tailor.py can do it.
cheers,
martin
Hi,
Quoted 1 line · Martin Langhoff
+ Can I import from others? Maybe -- check if
tailor.pycan do it.
+ What is tailor.py? http://www.darcs.net/DarcsWiki/Tailor.
Hth,
Dscho
How old linus bk repos have been import to git ?
Quoted 8 lines · Johannes Schindelin
Hi,
Quoted 1 line · Martin Langhoff
+ Can I import from others? Maybe -- check if
tailor.pycan do it.+ What is
tailor.py? http://www.darcs.net/DarcsWiki/Tailor.
Quoted 8 lines
Hth,
Dscho-
To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to [email protected]
More majordomo info at http://vger.kernel.org/majordomo-info.html
--
Beber
#e.fr@freenode
Hi,
Quoted 1 line · Bertrand Jacquin
How old linus bk repos have been import to git ?
Using the CVS gateway, via git-cvsimport.
Hth,
Dscho
Quoted 3 lines
I'll try to add questions from the archives of this ml, I'm also open to any suggestions.
This is sort of the "missing" paragraph from the "git-checkout" man page. It's there now, but in the "-m" option.
jdl
Q. Why won't git let me change to a different branch
using "git checkout <branch>" or "git checkout -b <branch>"? Instead it just says:
fatal: Entry 'foo.c' not uptodate. Cannot merge.
A. You have changes to files in your working directory that
will be overwritten, removed or otherwise lost if the checkout and change to the new branch were to proceed. To fix this you may either check your changes in, create a patch of your changes and revert your files, or use the "-m" flag like this:
git checkout -m -b my-branch